AdminSendProductRatingEmailToOneUserWorkflowHandler là trình xử lý workflow dùng để gửi email mời một người dùng đánh giá sản phẩm. Handler này thường được chạy trong một workflow marketing: hệ thống lấy danh sách người tham gia từ participant segment, duyệt từng user, tạo link đánh giá sản phẩm, rồi gửi email theo mail template.
Tên handler cần cấu hình trong workflow step là:
send_product_rating_email_to_one_user

Mục Đích

Handler này phục vụ luồng gửi email thu thập đánh giá sản phẩm sau khi người dùng đã mua, dùng thử hoặc tương tác với sản phẩm.
Email được gửi đến từng user, kèm theo các dữ liệu như:
  • thông tin user,
  • tên sản phẩm,
  • ảnh sản phẩm,
  • URL website,
  • link đánh giá sản phẩm,
  • metadata campaign participant segment để theo dõi chiến dịch.

Điều Kiện Để Handler Chạy Đúng

Workflow step phải dùng handler name:
send_product_rating_email_to_one_user
Participant segment phải có participantType là:
users
Participant trả về từ script nên có dạng khuyến nghị:
[lastId, userId, email]
Trong đó:
  • lastId: ID dùng để phân trang segment.
  • userId: ID user thật trong hệ thống.
  • email: email nhận thư.
Handler cũng hỗ trợ dạng ngắn hơn: 
[userId]
[userId, email]
Nhưng với workflow executor hiện tại, dạng [lastId, userId, email] là phù hợp nhất vì executor dùng participant[0] làm page token và participant[1] làm participant id khi lưu thống kê.

Luồng Hoạt Động

flowchart TD
    A[Workflow executor quét workflow run ACTIVATED] --> B[Lấy campaign participant segment]
    B --> C[Lấy participant segment và fetchParticipantsScript]
    C --> D[Query tối đa 100 participants theo lastId]
    D --> E[Duyệt từng participant]
    E --> F[Gọi handler send_product_rating_email_to_one_user]
    F --> G{participantType là users?}
    G -- Không --> H[Trả về lỗi]
    G -- Có --> I[Lấy userId và email]
    I --> J[Load user]
    J --> K[Load product theo productCode]
    K --> L[Tạo ratingLink]
    L --> M[Đổ tham số vào mail template]
    M --> N[Gửi templated email]
    N --> O[Ghi log kết quả]

Cách Handler Tạo Email

Khi nhận input từ workflow executor, handler sẽ:
  1. Kiểm tra participant type phải là users.
  2. Lấy userId từ participant.
  3. Lấy email từ participant, nếu không có thì dùng email trong hồ sơ user.
  4. Đọc parameters của workflow run.
  5. Kiểm tra productCode.
  6. Tìm sản phẩm theo productCode.
  7. Lấy ảnh banner của sản phẩm nếu có.
  8. Lấy webUrl từ setting hệ thống.
  9. Tạo link đánh giá theo dạng:
{webUrl}/ezyrating/user-ratings/products/{productCode}?fromUserUuid={userUuid}
Nếu user có display name, link sẽ thêm:
&fromUserDisplayName={encodedDisplayName}
Sau đó handler gửi email bằng mail template.

Các Tham Số Chạy Workflow

Khi tạo hoặc chỉnh sửa Workflow Run, trường parameters cần là JSON object hợp lệ.
Ví dụ tối thiểu:
{
  "productCode": "PRODUCT_CODE"
}
Ví dụ có chỉ định template:
{
  "productCode": "PRODUCT_CODE",
  "mailTemplateName": "user_product_rating"
}
Các tham số quan trọng:
Tham sốBắt buộcMặc địnhÝ nghĩa
productCodeCóKhông cóMã sản phẩm cần thu thập đánh giá. Handler dùng mã này để load sản phẩm và tạo link đánh giá.
mailTemplateNameKhônguser_product_ratingTên mail template dùng để render email. Nếu truyền chuỗi rỗng thì handler báo lỗi.
Các tham số được handler tự động thêm vào template:
Tham sốÝ nghĩa
userObject user đầy đủ.
userDisplayNameTên hiển thị của user.
userEmailEmail trong hồ sơ user.
userPhoneNumberSố điện thoại user.
userUuidUUID của user.
productNameTên sản phẩm.
productImageObject media banner của sản phẩm, nếu có.
productImageUrlURL ảnh sản phẩm, hoặc giá trị null-string nếu không có ảnh.
webUrlURL website lấy từ setting hệ thống.
ratingLinkLink để user đánh giá sản phẩm.
Lưu ý: không nên truyền locale bằng JSON string trong workflow parameters, vì handler cast trực tiếp sang Locale. Nếu cần locale, nên inject bằng code hoặc mở rộng handler cho case này.

Cấu Hình Workflow Run

Các trường chính khi tạo Workflow Run:
TrườngÝ nghĩa
workflowIdWorkflow chứa step gửi email.
campaignParticipantSegmentIdSegment người nhận thuộc campaign.
typeKiểu chạy: ONE_TIME, LOOP, hoặc CONTINUATION.
priorityĐộ ưu tiên của run.
cronExpressionLịch chạy, dùng cho LOOP hoặc CONTINUATION. Ví dụ 0/30 * * * * *.
parametersJSON chứa productCode và tuỳ chọn mailTemplateName.
statusNên đặt ACTIVATED để executor có thể chạy.
Workflow, workflow step và workflow run đều cần ở trạng thái kích hoạt phù hợp. Nếu workflow run là ONE_TIME, sau khi chạy xong hệ thống sẽ đánh dấu completed. Với LOOP hoặc CONTINUATION, hệ thống tính nextRunTime dựa trên cron expression.

Mail Template Cần Có

Template mặc định là:
user_product_rating
Template có thể dùng các biến như:
Tên biến cụ thể phụ thuộc engine render mail template, nhưng dữ liệu đã được handler đưa vào parameters.

Các Kết Quả Và Lỗi Thường Gặp

Handler trả về chuỗi kết quả để executor ghi log:
Kết quảNguyên nhân
send mail successfullyGửi email thành công.
participantType is emptyParticipant type không phải users.
participant is invalidParticipant không phải mảng object.
participants is invalidParticipant rỗng.
user id: ... is invalidKhông tìm thấy user.
user email is emptyKhông có email nhận thư.
mailTemplateName is emptyTemplate name bị rỗng.
productCode is emptyThiếu productCode trong parameters.
product with code: ... not foundKhông tìm thấy sản phẩm theo mã.

Gợi Ý Cấu Hình Nhanh

Workflow step:
handlerName = send_product_rating_email_to_one_user
status = ACTIVATED
Workflow run parameters:
{
  "productCode": "demo-product",
  "mailTemplateName": "user_product_rating"
}
Participant segment:
participantType = users
Script lấy participant nên trả về mỗi dòng theo dạng:
[lastId, userId, email]
Với cấu hình này, mỗi participant hợp lệ sẽ nhận một email mời đánh giá sản phẩm, trong đó link đánh giá đã gắn productCode, userUuid và tên hiển thị của user nếu có.